Aminet 3/Aminet 3 - July 1994.iso/Aminet/mus/misc/xmodule26b.lha/XModule/XModule.doc

Text File | 1994-04-06 | 19KB | 434 lines

   This manual documents XModule version 2.5 released on 15 Apr 94.

   Copyright (C) 1993-1994 by Bernardo Innocenti, Freely distributable,
all rights reserved.

Overview
********

   The Amiga computer has standard file formats for almost everything.
Graphics, text, animation, hypertext and many other data types are
easily imported into any program that supports the given standards.
But this isn't true for music.  Too bad the music interchange file
format defined by Electronic Arts (the old IFF SMUS) was too poor to be
usable in high-quality music sequencers.  Therefore, every music editor
created its own proprietary module format, so that, for instance, you
cannot load into ProTracker music written with Oktalyzer.

       XModule (pronounced Cross Module) is a music module
conversion utility that tries to solve this problem.  The project
started in early 1993, as a friend of mine (Fabio), who wrote a lot of
(good) music on Oktalyzer, needed ProTracker to obtain certain effects.
He had an old PD conversion program called `Tracker' that worked only
in particular conditions and was really bogus.  So I decided to contact
the author and he let me have the source for Lit30000  (about $20).

   The original program has been completely rewritten from scratch, as
the source was really poorly coded.  At the moment, Oktalyzer,
ProTracker, NoiseTracker and SoundTracker are the only supported
formats, but I'm still developing XModule, so contact me if you want to
see your favorite music editor added to this (short) list (see Author).

   Now XModule sports many other features, like module optimization, a
nice user interface and complex module editing.  This is why I like to
call XModule a module processor.  XModule is to the music processing
what ADPro and ImageFX are to image processing (am I a bit immodest?).

Distribution
************

   XModule is a Freeware program.  This means that you (probably)
have got it free and you should not ask any money if you decide to
copy it for someone else.  If, instead, someone sold you XModule for a
price higher than the media used to store it on (i.e. $1 for a DD
disk), tell him he should try making money honestly.

   I'm not asking you to pay for XModule because I never paid for a
ShareWare program, so I felt that I somehow had to pay my debt: so I
decided to distribute XModule as free software, a little gift to all
the Amiga community.  Feel free to distribute XModule to your friends
and enemies, but, if you do so, you must keep the documentation and
the other distribution files together with the executable.  The source
code is not required, but I'm distributing it to let others take
advantage of my work, so, if possible, try to include the source too.

   Fred Fish, SAN and ADS are especially granted permission to include
XModule into their PD libraries.  Other PD libraries are welcome too.

   If you intend to include XModule or parts of it in a commercial
package, please at least send me a free copy.  I would be honored to
see one of my programs being part of a commercial package.

   You can modify or improve XModule (see Programmers), only be so kind
to return the new source code to me, so I can put the new features in
the next release.  And, please, do not strip my name from the
documentation, the program source, or the executable.

   This product is provided as is without warranties of any kind: the
author of this program cannot be held liable for any defects in the
executable nor in the documentation or in any other files contained in
this package.  Any damage directly or indirectly caused by the
use/misuse of XModule is the sole responsibility of the user her/him
self.  In other words: XModule never formatted my hard disk nor killed
my dog, so I suppose it won't cause any damage to your system either,
but, just in case, do not blame me if something nasty happens.

Usage
*****

   XModule requires KickStart version 2.0 or greater.  The reason is
that I hate programming on 1.3 and I won't do it any more.  If you still
haven't upgraded to 2.0, you'll miss the chance to run XModule and many
other wonderful programs.  So what are you waiting for?

   XModule also takes advantage of some 3.0 features, like DataTypes
and some user interface enhancements.

Getting Started
===============

   You can invoke XModule either from the Shell or Workbench.  XModule
accepts both command line and ToolTypes arguments.  Workbench and Shell
parameters are the same.  The full AmigaDOS template is:

     XModule FROM/M,PUBSCREEN/K,PORTNAME/K,DETACH/S

The FROM keyword specifies optional modules to load at startup time.
From Workbench, you multi-select module icons instead of specifying a
ToolType.

   Specifying the PUBSCREEN keyword, followed by a public screen name,
allows you to open XModule on an existing public screen.  The given
name should match exactly (case matters), or the system won't be able to
find the requested screen.  If the screen does not exist, a new public
screen will open, cloning Workbench resolution and palette.  Note that
this behavior is not standard: Commodore commodities will abort if the
required public screen does not exist.  Default for this option is
"Workbench" that opens XModule on the Workbench screen.

       PORTNAME will change the name of XModule's ARexx port.  If a
port with this name already exists, a number (eg: ".1") will be
appended to the name, until a unique name is found.  The port name
defaults to "XMODULE".  For more about the ARexx port, consult the
ARexx Interface chapter.

   The DETACH switch allows you to detach XModule from the Shell it
was started from.

User Interface
==============

   XModule's GUI follows Commodore's 2.0 style guidelines.  Under
Kickstart 3.0 and above, XModule takes advantage of some new OS
capabilities.

   Gadget layout is font sensitive, but using some fancy fonts could
give you a strange user interface look.  If you use a very big font and
a window becomes too big to fit the screen, topaz 8 will be used for
rendering that window.

   In all windows, the following shortcut keys are active:

ESC
     Close the active window.  Does not work with ToolBox Window.

HELP
     Bring up AmigaGuide on-line help.  This feature requires
     amigaguide.library.

TAB
     Cycle forward through string and numeric gadgets within the active
     window.  SHIFT-TAB cycles backwards.

   In addition, gadgets with underscored characters in labels, can be
selected hitting the highligted key.

Panels
======

   Sorry, XModule's documentation is still incomplete.  The next release
will hopefully be more accurate.

   But wait! Do not commit suicide for such a reason: XModule is very
easy to use, and you will be able to operate it even without this
chapter.

Format Conversion
*****************

   XModule can load and save modules created by other music editors.
The following is a list of supported module formats:

* Noise Tracker
     Noise/ProTracker 31 instruments module.  This is the default.

* ProTracker 2.3
     ProTracker 2.3 new 100 patterns module.  XModule will automatically
     switch to Pro Tracker 100 whenever the converted module exceeds
     the 64 patterns limit.

         Warning: You must load such a module with ProTracker 2.3 or
     better in order to play/edit it.  Older players will either refuse
     to load or turn the module into scratch dance.

* Sound Tracker 15 instrument module
     This is pretty useless as SoundTracker is becoming quite rare.  Do
     not save SoundTracker modules unless you really need to, because
     most players/editors will stop supporting this format very soon.
     SoundTracker format has no way of identifying a module, therefore
     XModule will ask you to confirm a SoundTracker module when the
     file being loaded matches no other module format.

* Oktalyzer V1.1
     Oktalyzer is an old editor which can play up to 8 channels by
     mixing instruments in real time.

   As a matter of fact, there are things that simply cannot be done
because of the big differences between module formats.  Below is a list
of the internal limitations of each module formats, when saving to a
particular format, if the module exceeds one of this values, or makes
use of features not implemented, some data will be stripped away to
produce at least a partial conversion.


     Program          Instr  MaxPatt PattLen SongLen InstrLen
     --------------------------------------------------------
     Oktalyzer         36      128     128     128     128K
     Sound Tracker     15       64      64     128     128K
     Noise Tracker     31       64      64     128     128K
     Pro Tracker       31      100      64     128     128K
     MED/OctaMED       63      256     256     256     ???

     Where:
     #Instr   is the maximum number of instruments,
     MaxPatt  is the maximum number of patterns,
     PattLen  is the maximum number of lines per pattern,
     SongLen  is the maximum number of positions in a song,
     InstrLen is the maximum size of an instrument in bytes.

   Effects are the hardest thing to convert.  While Speed and Volume
are almost the same between different music editors, some effects (such
as Oktalyzer's H and L) cannot be converted because there are no
equivalents in other music editors.  Therefore, you will have to modify
the score manually if you intend to convert a module while keeping such
effects.  In addiction, some effects behave in different ways even if
they claim to do the same thing.

   Last but not least, some music editors support synthetic or hybrid
instruments.  Fortunately, none of the module formats known by XModule
implement such instruments, because I can hardly think of a way to
implement a sample to synthetic conversion (any ideas?).  I used to
like synthetic music, but it seems that all those great composers on
the good old C64 have disappeared...  Why have you musicians become so
lazy? 8-(

Optimization
************

   Module optimization is achieved by removing all unused data in such
a way that the module will sound the same as before.  XModule can
process a module to reduce its size as much as possible.  It is
generally a good idea to optimize a module before distributing it, but
never while you are composing it, because you could easly loose some
data that you didn't mean to discard.  Do not expect to gain a lot
optimizing a module: saving 20% of the total size is usually a very
good result.

* Unused patterns
     Some formats (e.g.: Sound/Noise/ProTracker) store empty patterns
     in a module if a pattern with a greater number is used.  For
     instance, a song using patterns 1, 2 and 5 will contain patterns 3
     and 4 as well.

         Warning: If a song contains a part that has not been finished
     yet and has not already been inserted in the position table, you
     will lose it.

         Warning: When a song is saved to Noise/ProTracker, patterns
     beyond the last used patterns are discarded regardless of this
     switch.  This is due to a limitation of Noise/ProTracker module
     format.

* Unused instruments
     A composer may decide to use an instrument and then change his
     mind, but forget to clear the instrument.  In this case the module
     will contain an instrument that is never played.  These instruments
     are simply stripped away.

* Sample data after a loop
     The part of an instrument following a loop is never played and is
     therefore discarded.

* Instruments zero tails
     Long zero tails eat up memory and produce no sound.  This
     optimization is performed only on loopless instruments, as a zero
     sequence inside a loop does make difference.  XModule leaves at
     least two zero bytes to avoid the nasty click produced by the
     speaker dropping its volume to zero too quickly.

ARexx Interface
***************

   Sorry, XModule's documentation is still incomplete.  The next release
will hopefully be more accurate.

   Anyway, XModule's ARexx port is not fully operative at the moment,
so you're not missing a great deal.

Known Bugs
**********

   Murphy's laws states that nothing can be perfect, even computer
programs.  XModule is far from being perfect and I need your help to
fix as many bugs as possible.  If you discover a bug not reported in
the list below, please notify me.

   When you report a bug, state exactly what happens and indicate how
to reproduce the conditions that generated the problem.  Reports like
`XModule sometimes crashes converting my favorite module' does not help
at all.  Include your name if you want to be credited in future XModule
releases.

   If the program refuses to convert a module, mail it to me on a disk
or upload it to a BBS that I can reach and I'll try to fix the problem
as soon as possible.  Glass Globe BBS, whose address can be found in
the Author chapter, will do.  If you want the disk back with the fixed
version of XModule, send me a self-addressed envelope with enough
Italian stamps or enough money for a reply.

   XModule has been tested on several machines running KickStart 2.0
and 3.0.  It should work on any 68K family processor (tested on 68000,
68020 and 68040) and is Enforcer and Mungwall proof.

Future plans
************

* OctaMED
     This will probably be the next format I'll work on.  I think this
     is the best music editor available on the Amiga, but I haven't yet
     got enough infos on its file format to code a conversion routine.
     If you have such information, please contact me (see Author).

* TeX
     Another format I would like to add is AmigaTeX.  If you know TeX,
     you will surely be wondering what a typesetting program can be
     used for in music.  Well, AmigaTeX is at the moment is the best
     implementation available on any computer of the TeX typesetting
     program, and its distribution includes MusicTeX, a powerful
     music language which can output notes in a great standard staff
     notation.  I know no other program on the Amiga that can print
     notes of such fine quality (if you do, let me know!), so I think
     that many musicians would appreciate such an option.

* Other module formats
     If you have documentation regarding a format you would like to see
     in a next release, please send it to me together with a couple of
     modules and, if possible and legal, the program that created them.
     I'll try to implement the new format only if it is somewhat easy:
     it is very hard to convert, say, Future Composer to SoundTracker.
     Do not send a module without a text file describing its structure,
     as I'm not willing to spend my nights hex-dumping modules :).

How to contact the author
*************************

   If you want to make me aware of your suggestions, bug reports, ideas
or you want to send me a gift, a good module or some money :-), reach
me in any of the following ways:

* Mail
          Bernardo Innocenti
          Via Ventiquattro Maggio, 14
          50129 - Firenze
          ITALY

* FAX
          [phone]
          Attn:  Bernardo Innocenti
          Subj:  Amiga/XModule

* E-Mail
          AmigaNet: Bernardo Innocenti 39:102/201.4
          FidoNet:  Bernardo Innocenti 2:332/118.4
          InterNet: [e-mail]
          (Glass Globe BBS [phone])

   I will try to reply to all my E-Mail, but I'm too lazy to reply
old-style mail.  Your suggestions will be taken into account unless
they are `I want XModule to do ice tea'-style.

Programmer notes
****************

   XModule has been written in C and compiled with SAS C version 6.51,
Other compilers may require some changes to the source.

   The program is written respecting the Amiga multitasking system and
following Commodore guidelines.  All allocated resources will be
(hopefully) freed before program termination.  I wrote XModule with the
goal in mind of keeping the executable fast and small.

   This manual has been typeset using MakeInfo, a GNU PD utility ported
to the Amiga by Reinhard Spisser and Sebastiano Vigna.  I found that
the time I saved writing one file for three was nearly compensated by
the time I spent learning how to operate MakeInfo.  As I'm not that
skilled in using TeX and MakeInfo, you will probably find this document
a bit silly in its typesetting style.

   Besides, English is not my first language (as you might have
guessed) and I bet this document is full of grammar mistakes.

   If you intend to translate, improve or somewhat edit this document,
please work on the supplied TexInfo file and then process it with the
utilities supplied in the MakeGuide distribution.  You can find
MakeGuide in several PD libraries such as BBSs.

   Do not hesitate to send criticisms to my work, and, even better,
advices on how to improve the program and the documentation.  See
Author.

Credits
*******

   * Fabio Barzagli, for beta testing version 1.x, for the money he
     paid me for it and, last but not least, for letting me have (or
     steal?) his awesome modules!

     Keep on making good music, Fabio!

   * Alessandro Lombardi, for 2.x beta testing.

     Stop deleting files!

   * Massimo Brogioni, for being my fido boss and for spreading bogus
     XModule releases all around the world.

     Hey boss, have you got a spare 5Gig streamer?

   * Erno Tuomainen for his wonderful Finnish BBS, for his kindness and
     for all the support he gave me.

     Are there any more top-rating modules to leech?

   * Gerardo Iula, for letting me have the source of Tracker (by paying
     :-( ).

     I assumed the money I paid covered the rights of modifying the
     original source and distributing modified versions of your
     program.  Hope you won't worry about it, Gerardo.

   * Sebastiano Vigna & his buddy Reinhard Spisser, for porting GNU
     MakeInfo to the Amiga and for Reinhard's E-Mail technical support.

     Please, continue developing this useful (and hard to learn) tool.
     By the way, MakeInfo crashed my Amiga really bad a couple of times!
     Are my docs that boring?

   * The Amiga, for being the best computer in the world. :^)

     Commodore: Why don't you sell the Amiga project to someone serious
     such as GVP or NewTek?